Avalara AvaTax Setup

Overview: This document provides the steps needed to configure Order Management System to integrate with Avalara AvaTax so that AvaTax calculates tax for orders during order entry, pick slip preparation, and billing.

Compatibility: Order Management System version 17.0 and later is compatible with Avalara AvaTax REST API v2.

In this chapter:

• Before You Start: Taxability Considerations:

- Mapping Data from Order Management System to AvaTax

• Configuration Steps:

- Setup within Order Management System

- Set up Data within AvaTax

• Configuration Files

- Proxy Settings

- WebService Mapping File

- AvaTax Values by Company Properties File

For more information: See Avalara AvaTax Interface for an overview on the integration.

Before You Start: Taxability Considerations

Mapping Data from Order Management System to AvaTax

Before you start the configuration steps described below, it is helpful to note the information in Order Management System that maps to corresponding values in AvaTax.

OROMS	AvaTax	Notes
company (WCMP)	taxpayer	Typically, the Order Management System company code matches the AvaTax taxpayer code; however, if you specify a default_company in the AvaTaxValues_999.properties file, it overrides the actual company code. You might define a company override if the AvaTax taxpayer is already set up in AvaTax and you need to configure Order Management System to map to the existing taxpayer.
entity (WENT)	taxpayer	Used if the Pass Entity Code to Tax Interface (F69) system control value is selected, indicating you want to report taxes by entity. In AvaTax, set up the company taxpayer as the parent, and configure all required data at the entity-level taxpayer (child). Typically, the Order Management System entity code matches the entity-level (child company) AvaTax taxpayer code; however, if you specify an entity_999_child_company in the AvaTaxValues_999.properties file, it overrides the actual entity code. You might define an entity override if the AvaTax taxpayer is already set up in AvaTax and you need to configure Order Management System to map to the existing taxpayer. The entity on an order is determined by the division assigned to the source code on the order header.
item class (WICL)/ long SKU department (WLSD)/ long SKU division (WLSV)/ long SKU class (WLSC)	product class	Assigned in Order Management System to the item/SKU (MITM). Used to map to the tax code in AvaTax in order to apply tax rules and exemptions. You can create a cross-reference between a tax product code and an item class, long SKU division, long SKU department, and long SKU class combination using the Working with Tax Product Code Cross References (WTPC) menu option.
customer class (WCCL)	customer class	Assigned in Order Management System to the customer. Defined in the AvaTaxValues_999.properties file. Maps to the tax code in AvaTax to apply tax rules and exemptions. Note: • You can also flag specific customers as tax-exempt in Order Management System by specifying an Exempt certificate number and Exempt expiry date. • If the customer on an order is assigned to a customer class in Order Management System that does not correspond to a matching tax code in AvaTax, AvaTax calculates tax based on the tax code assigned to the product class.

Configuration Steps

Setup within Order Management System

AvaTax Account ID and License

Use the AvaTax Account (M37) and AvaTax License (M38) system control values to specify a company-specific account ID and license ID used for communication with AvaTax.

If a company-specific account ID and license ID is not defined, the system uses the AVATAX_ACCOUNT and AVATAX_LICENSE properties in Working with Customer Properties (PROP) for communication with AvaTax.

The system encrypts the license ID entry.

System Control Values

• AvaTax Account (M37): Enter the company-specific account ID used for communication with AvaTax. If you leave this blank, the system uses the account ID defined in the AVATAX_ACCOUNT property.

• AvaTax License (M38): Enter the company-specific license ID used for communication with AvaTax. If you leave this blank, the system uses the license ID defined in the AVATAX_LICENSE property. The system encrypts this value.

• Use Generic XML Tax Interface (J10): Must be selected to have Order Management System communicate with AvaTax.

• Use Standard Tax Calculation if Tax Interface Fails (J13): Select this value to have Order Management System use the standard tax calculation if it does not receive a response from AvaTax. If you select this value, you will need to set up tax rates at the SCF level (WSCF) and/or the postal code level (WZIP).

• Pass Entity Code to Tax Interface (F69): Select this value to pass the entity associated with the source code on the order header to AvaTax,. If you select this value, then you can set up product class or customer class tax exemptions at the entity level in AvaTax. In AvaTax, set up the company taxpayer as the parent, and configure all required data at the entity-level taxpayer (child). Typically, the Order Management System entity code matches the entity-level (child company) AvaTax taxpayer code; however, if you specify an entity_999_child_company in the AvaTaxValues_999.properties file, it overrides the actual entity code. You might define an entity override if the AvaTax taxpayer is already set up in AvaTax and you need to configure Order Management System to map to the existing taxpayer.

• Tax Included in Price (E70): Must be unselected if your company integrates with AvaTax.

• Send Tax to Tax Interface as Quote not Invoice (L11): Indicates whether billing should send a quotation or an invoice request message to AvaTax when processing a shipment or a return.

Note:

• When you change a system control value, stop and restart the background jobs (MBJC) and exit and re-enter Order Management System to have your changes take effect.

• It is not necessary to set up the Tax on Freight (B14) or Tax on Handling (B15) system control values.

TAX_INT Integration Layer Job (IJCT)

For the TAX_INT job: Set the Communication type to Web Service and set the WSDL Document Name to CalculateTax70.wsdl. Note: The system requires a value in the WSDL Document Name field, but the wsdl is not used by the interface.

Because the TAX_INT job is always in INTERACT status, you do not stop or restart the job for your change to take effect.

Note: The TAX_INT job does not require a process queue.

Customer Class for Exempt Customers

Use the Work with Customer Class (WCCL) to set up one or more classes of customers who are tax exempt, and then assign customers in Order Management System to the appropriate customer class. You can then set up the customer class(es) as tax exempt in AvaTax. Similarly, set up tax product code exemptions in AvaTax and define a tax product code cross reference in the Working with Tax Product Code Cross References (WTPC).

Note: If the customer on an order is assigned to a customer class in Order Management System that does not correspond to a matching class in AvaTax, AvaTax calculates tax as if there is no customer class assignment.

Specific Customer Tax Exemptions

Use Work with Customers (WCST) to set up specific customers as tax exempt, including specifying their Exempt certificate number and the Exempt expiry date, or setting this information up for the customer in specific states or provinces. Order Management System passes this information to AvaTax when a tax exempt customer places an order. It is not necessary to assign these customers to a particular customer class in order to flag them as tax exempt to AvaTax.

Tax Product Codes

Use Work with Items/SKUs (MITM) to assign items and SKUs to an item class, long SKU department, and long SKU class and define a cross reference to a tax product code in AvaTax.

Note: It is not necessary to set up tax rates or other settings at the SCF level or the postal code level if you are using the generic tax integration with AvaTax.

Warehouse Address

Use Work with Warehouses (WWHS) to define an address for each warehouse used for items that require tax.

Set up Data within AvaTax

Companies and Entities

Use the Organization tab within Avalara AvaTax to set up company and entities as companies in AvaTax:

1. Set up an AvaTax company for each company to integrate with AvaTax. The AvaTax company code should match the Order Management System company code and should be zero-filled (for example, company 3 in Order Management System = company code 003 in AvaTax). Assign the company code to the appropriate jurisdictions, such as all U.S. states.

2. If you are sending entity information to AvaTax, add an AvaTax company for each entity for the related Order Management System company, where the Order Management System company is the parent company to the entity company. For example, if you are adding entity 100 for company 3, select company 003 in AvaTax as the parent for company 100. Again, assign the company to the appropriate jurisdictions, such as all U.S. states.

Note: If the Order Management System company code does not match the company code in AvaTax, set up default values in the AvaTaxValues_999.properties file.

Tax Jurisdictions

For each AvaTax company, use the Nexus Jurisdictions option to define where AvaTax calculates tax.

Custom Tax Codes

For each AvaTax company, use the Custom Tax Codes option to define custom tax codes for a product, service, or charge.

Custom Tax Rules

For each AvaTax company, use the Custom Tax Rules option to define tax rules for a specified country, tax level (state, county, city, special tax jurisdiction), and region.

Items

For each AvaTax company, use the Items option to map your items to tax codes.

Note: Use the Working with Tax Product Code Cross References (WTPC) menu option as your master list for mapping; any mapping you define in AvaTax will override the mapping in the Working with Tax Product Code Cross References (WTPC) menu option.

For more information: See the AvaTax documentation for more information on the set up required in AvaTax.

Configuration Files

Use a text editor to edit the following files.

Important: Make a backup copy of each of the files discussed below before making any changes. Also, it is important that you do not make any changes in these files beyond those outlined in these instructions.

Proxy Settings

When communicating with AvaTax, you must define a proxy server to act as an intermediary in order to increase security. Order Management System sends transactions to the proxy server and the proxy server sends the transactions along to Vertex. The PROXY_HOST and PROXY_PORT properties in Working with Customer Properties (PROP) define the IP address and port number used to connect to the proxy server during tax calculation.

WebService Mapping File

Purpose: This file contains information required for the AvaTax web service. The AvaTax web service runs outside of Order Management System and is used to transmit information between AvaTax and Order Management System.

File location: This file is typically located on the application server at /domain/conf/cwdirectcpproperties/webservicemapping.properties, where domain is the WebLogic domain directory for Order Management System.

Note: This file is delivered with Order Management System and should not be changed.

Property Name	Description
TAX_INT	This setting indicates Order Management System communicates with AvaTax. The setting for AvaTax production is: com.mr.interfaces.avatax.AvaTaxWS The setting for AvaTax test is: com.mr.interfaces.avatax.AvaTaxWSTest

AvaTax Values by Company Properties File

Purpose: Use this file to specify default values to send to AvaTax for each company that will use the tax integration.

File name and location: An AvaTaxValues.properties file is delivered with the application.

• If you wish to define specific settings for a company, create a copy of the file and name it AvaTaxValues_999.xml, where 999 is the company code. The company number in the file name should be zero-filled; for example, the file name for company 1 is AvaTaxValues_001.xml

• If you do not define an AvaTaxValues.properties file for a specific company, the system uses the settings in the generic AvaTaxValues.properties file.

The files are typically located on the application server at /domain/conf/cwdirectcpproperties/AvaTax/, where domain is the WebLogic domain directory for Order Management System.

Configuring the file: Each entry in the file is labeled by an ID, for which you enter the corresponding Value.

Note: After making any change to the file, you need to restart Order Management System to have your changes take effect. See Restarting Order Management System for more information.

Default Value ID	Value
default_company	If the Order Management System company code differs from the actual company value in AvaTax, use this field to enter an override company code to pass to AvaTax. Leave this field blank to pass the actual Order Management System company code to AvaTax. This value is mapped to the companyCode in the AvaTax Request message if the entity_999_child_company setting is blank.
entity_999_child_company (where 999 is the Order Management System entity code)	If you are configured to use entity and the entity defined in Order Management System does not match the value defined in AvaTax, use this field to enter an override entity code to pass to AvaTax. Leave this field blank to pass the value in the default_company field to AvaTax. If the default_company field is blank, the system passes the actual Order Management System company code to AvaTax. Note: There can be multiple records for this property value. This value is mapped to the companyCode in the AvaTax Request message.
default_warehouse_line1	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the line1 field in the ShipFrom section of the AvaTax message.
default_warehouse_line2	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the line2 field in the ShipFrom section of the AvaTax message.
default_warehouse_line3	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the line3 field in the ShipFrom section of the AvaTax message.
default_warehouse_city	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the city field in the ShipFrom section of the AvaTax message.
default_warehouse_state	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the region field in the ShipFrom section of the AvaTax message.
default_warehouse_country	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the country field in the ShipFrom section of the AvaTax message.
default_warehouse_postalcode	Used to populate the ShipFrom address fields in AvaTax message. If the ship_from_warehouse is 000 in the CWTaxRequest message, the system uses this value to populate the postalcode field in the ShipFrom section of the AvaTax message.
call_center_line1	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the address line 1 field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_line2	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the address line 2 field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_line3	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the address line 3 field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_city	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the city field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_state	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the state field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_country	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the country field in the PointOfOrderAcceptance section of the AvaTax message.
call_center_postalcode	Used to populate the PointOfOrderAcceptance address fields in AvaTax message. The system uses this value to populate the postalcode field in the PointOfOrderAcceptance section of the AvaTax message.
order_freight_tax_code	Used to populate the AvaTax tax code for Order Freight. The system uses this value when the line item type is OF (order freight).
line_duty_tax_code	Used to populate the AvaTax tax code for Line Duty. The system uses this value when the line item type is LD (line duty).
line_handling_tax_code	Used to populate the AvaTax tax code for Line Handling. The system uses this value when the line item type is LH (line handling). Note: If the S/H exclude tax? flag is selected for an additional charge code, then a line that uses this additional charge code for special handling is not subject to order line handling (LH) tax. See Establishing Additional Charge Codes (WADC) for background.
additional_freight_tax_code	Used to populate the AvaTax tax code for Additional Freight. The system uses this value when the line item type is AF (additional freight and shipper item charges).
line_freight_tax_code	Used to populate the AvaTax tax code for Line Freight. The system uses this value when the line item type is LF (line freight).
customer_usage_type_CC (where CC is the Order Management System customer class code)	Defines the customer usage type value for each customer class. Note: There can be multiple records for this property value.
tax_date	Used to determine the tax date during billing. Valid values are: • I = Invoice; use invoice tax calculations during billing. • O = Order; use order tax calculations during billing.